Skip to main content

Aventora API Security Policy

FieldValue
Version1.0
Effective dateJuly 6, 2026
OwnerEngineering Leadership
Review cadenceAnnually, and upon material changes to API architecture, authentication models, or public integration surfaces

This document defines Aventora’s official API security requirements and describes operational practices for APIs developed or operated by Aventora. It applies to Engagement Hub, Domain Assistant, Aventora CRM, administrative applications, mobile clients, and supporting integrations.

This policy supports enterprise security reviews and aligns with common control themes found in SOC 2 and OWASP API Security guidance. Aventora does not claim formal certification under SOC 2, ISO 27001, or other frameworks based on this document alone. Deployment-specific implementation may vary by hosting model (managed cloud, customer self-hosted Docker, or private cloud).

1. Purpose​

The purpose of this API Security Policy is to define security requirements for all internal and external APIs developed or managed by Aventora.

These requirements ensure that Aventora platform APIs—including REST endpoints, internal service-to-service calls, webhook receivers, GraphQL APIs where applicable, and WebSocket channels—are designed, implemented, deployed, and operated with consistent protections against unauthorized access, data exposure, abuse, and integration risk.

This policy provides a common reference for engineering, operations, and customer security teams when reviewing API posture, onboarding integrations, or evaluating Aventora deployments.

2. Scope​

This policy applies to the following API categories across Aventora-managed and Aventora-supported deployments:

CategoryExamples
REST APIsEngagement Hub (Aventora-Assistant), Domain Assistant (domain-chatbot), Aventora CRM (/rest/...)
Internal service APIsHub ↔ Domain Assistant calls, CRM ↔ Hub engagement proxies, worker-to-API internal routes
Public APIsHealth checks, provider webhooks (Twilio, Square), optional unauthenticated submission and query endpoints with explicit rate controls
AI service APIsLLM provider integrations (OpenAI, Groq) invoked server-side during active sessions
Mobile APIsEngagement Hub mobile routes consumed by Aventora Hub mobile clients
Web application APIsAdmin portal BFF routes (aventora-admin), CRM GraphQL and REST, browser-consumed platform APIs
Third-party integrationsTelephony (Twilio, Telnyx), calendar OAuth (Microsoft, Google), CRM connectors, payment and commerce hooks

Customer-managed systems outside Aventora’s direct control remain the customer’s responsibility unless explicitly covered by a services agreement.

For endpoint-level authentication behavior, see API Security Model.

3. Authentication​

General requirements​

  • All production APIs require authentication unless explicitly designated as public (for example, health endpoints, provider webhooks validated by alternate controls, or documented optional-authentication flows with compensating rate limits).
  • Authentication uses approved identity mechanisms appropriate to each service:
    • API keys — Engagement Hub sensitive routes require Authorization: Bearer <api-key>. Keys are stored as SHA-256 hashes; plaintext keys are shown once at creation.
    • JWT access tokens — Domain Assistant and CRM issue or validate JWTs for authenticated user and workspace sessions. Passwords are stored as bcrypt hashes.
    • Domain and platform API keys — Domain Assistant supports domain-scoped and platform-wide admin API keys for administrative and server-to-server operations.
    • Webhook signature validation — Inbound telephony and messaging webhooks validate provider signatures (for example, Twilio request validation) where supported.
    • Shared secrets — Selected server-to-server webhooks use configured secrets (for example, CRM engagement webhook headers).
  • Administrative APIs require MFA-protected accounts for production administrative access. The admin portal supports FusionAuth TOTP step-up when MFA_REQUIRED=true and FusionAuth is configured. MFA is also required for Aventora personnel on GitHub, AWS, and Google Workspace accounts used for development and operations.
  • Service credentials are securely managed — Secrets are managed through restricted deployment configuration and may use centralized vault services depending on deployment model. Server-to-server API keys for tenant and account scoping are stored in application databases, not in client applications.

Public and optional-authentication endpoints​

Some endpoints are intentionally reachable without user credentials but are not unprotected:

  • Health and readiness probes support operational monitoring.
  • Provider webhooks rely on signature validation or shared secrets rather than bearer tokens.
  • Selected Domain Assistant endpoints (for example, public query search and form submissions) accept optional JWT authentication; unauthenticated callers are subject to rate limiting.

New public endpoints require Engineering Leadership approval and documented compensating controls.

4. Authorization​

Aventora enforces authorization after authentication on protected API routes.

Requirements​

  • Role-Based Access Control (RBAC) — Authorization decisions use roles, permissions, and workspace or tenant scope:
    • Engagement Hub API keys are scoped by permission (for example, call_management, billing_access, admin).
    • Domain Assistant enforces admin and domain ownership checks.
    • Aventora CRM uses workspace role assignments and guards on /rest/... routes.
  • Principle of Least Privilege — API keys, service accounts, and integration credentials are granted the minimum permissions required for their function. Platform-wide admin keys are restricted to authorized administrative components and scripts.
  • Server-side authorization checks on every request — Sensitive routes use server-side dependency guards evaluated before business logic executes.
  • No client-side authorization decisions — Clients may hide UI elements by role, but access control is enforced exclusively on the server. Missing or invalid credentials result in HTTP 401; insufficient permissions result in HTTP 403.

Authorization coverage is implemented at the route level. Engineering teams must ensure new sensitive endpoints include appropriate auth dependencies before production release.

5. Transport Security​

All production API traffic must be protected in transit.

Requirements​

  • HTTPS only — Customer-facing and administrative APIs are accessed over HTTPS. Reverse proxies (Nginx or Caddy) terminate TLS with certificates (commonly Let’s Encrypt) and forward to application containers on localhost.
  • TLS 1.2 or higher — Reverse proxy TLS configuration supports TLS 1.2 and newer protocols.
  • No unencrypted API traffic in production — Application containers bind to localhost or private networks behind the reverse proxy. Direct HTTP exposure of production APIs on the public internet is prohibited.
  • Database and provider connections — PostgreSQL connections use TLS when the database provider or host configuration supports it. Third-party API and webhook communication uses provider HTTPS endpoints.

Internal development may use local HTTP for engineer workstations; production and customer-facing staging environments must use HTTPS.

6. Input Validation​

API inputs are validated before processing to reduce injection, logic abuse, and malformed payload risk.

Requirements​

  • Server-side validation — All externally supplied data is validated on the server. Client-side validation, where present, is supplementary only.
  • Schema validation — Application framework validators enforce type, format, and required-field constraints on request bodies, query parameters, and path parameters.
  • Business rule validation — Domain-specific rules (tenant scope, account ownership, permission requirements, template parameter constraints) are enforced in service layers after schema validation.
  • Sanitization where appropriate — User-supplied content destined for logs, exports, or external systems is handled with appropriate encoding and security-first formatting (for example, CSV export sanitization in CRM workflows).
  • Rejection of invalid requests — Validation failures return appropriate HTTP error responses (typically 400 or 422) without processing the invalid operation.

Webhook endpoints additionally validate provider signatures and reject requests that fail cryptographic verification.

7. Output Protection​

API responses must minimize unnecessary exposure of sensitive data and system internals.

Requirements​

  • Sensitive information is not unnecessarily returned — API responses include only fields required for the authorized operation. Credentials, full API keys, password hashes, and internal identifiers are excluded from routine responses. Hub API keys are displayed in plaintext only at creation time.
  • Error responses do not expose implementation details — Production error handling avoids returning stack traces, internal file paths, database errors, or dependency versions to API clients. Validation errors provide sufficient detail for legitimate clients without revealing internal architecture.
  • Security headers are used where applicable — Reverse proxies forward standard headers (X-Forwarded-For, X-Forwarded-Proto, Host) for correct client and scheme handling. Additional security headers (for example, HSTS, content security policies on web applications) are applied at the proxy or application layer where configured for the deployment.

Engineering teams must avoid verbose logging of request bodies, authorization headers, or personally identifiable information in production unless explicitly approved. See Logging and Audit.

8. Secrets Management​

API credentials and integration secrets must be protected throughout their lifecycle.

Requirements​

  • API keys stored securely — Hub API keys are persisted as SHA-256 hashes. Selected tokens (for example, inbound secure links) are hashed before storage. OAuth tokens and account-linked integration keys are stored using restricted database access and encryption mechanisms where supported by the deployment.
  • Secrets never committed to source control — Live credentials, API keys, and tokens must not be committed to repositories. Sample and template environment files use non-sensitive placeholders.
  • Credentials rotated when necessary — Secrets suspected or confirmed to be compromised are rotated promptly. API keys can be revoked and reissued through product administrative interfaces. Integration credentials are updated in environment configuration or database records as appropriate.
  • Restricted deployment configuration — Runtime secrets are supplied through restricted deployment configuration accessible only to authorized operations personnel. Centralized vault services may be used depending on deployment model.

9. Logging & Monitoring​

Aventora systems log authentication, authorization, and security-relevant API events to support monitoring and incident response.

Requirements​

  • Authentication events logged — Login attempts, token validation failures, and API key validation outcomes are recorded through application logging facilities.
  • Authorization failures logged — Permission denials and unauthorized access attempts are captured in application logs with request context (method, path, client IP) where available.
  • Security-related API events logged — Webhook validation failures, rate limit threshold breaches, worker authentication errors, and administrative API operations are logged for operational review.
  • Logs retained according to Aventora policies — Application logs use rotating handlers with configurable retention. Log access is restricted to authorized engineering and operations staff.

Configurable alert email recipients exist for selected operational events, including API rate limit breaches, provider failures, and integration errors.

Dedicated immutable audit ledgers may be implemented based on deployment scale and customer requirements. See Logging and Audit and Data Retention.

10. Rate Limiting & Abuse Protection​

Aventora implements rate limiting and abuse protections appropriate to API exposure and risk.

Application-layer controls​

  • Rate limiting implemented where appropriate — Examples include:
    • Engagement Hub API key hourly limits (API_KEY_RATE_LIMIT_PER_HOUR) with optional alert emails (RATE_LIMIT_ALERT_ENABLED).
    • Domain Assistant submission and query rate limits for unauthenticated callers.
    • CRM integration rate limits when calling external CRM APIs (TWENTY_CRM_RATE_LIMIT_PER_SECOND, TWENTY_CRM_RATE_LIMIT_PER_MINUTE).
    • Telephony and messaging throughput controls (for example, account-level SMS rate caps).
  • Protection against abuse and denial-of-service attacks — Unauthenticated public endpoints require rate limits or provider signature validation. Authenticated routes rely on permission scoping, key revocation, and operational monitoring. Background workers apply intelligent throttling for bulk operations.

Edge and infrastructure controls​

  • Reverse proxy controls — Nginx or Caddy reverse proxies terminate TLS and may enforce additional connection or request limits where configured for a deployment.
  • Cloudflare edge protections — Internet-facing Aventora-managed services may use Cloudflare (or equivalent CDN/WAF providers) for DDoS mitigation, edge rate limiting, and web application firewall rules where operationally deployed. Specific edge controls vary by hosting environment and are configured at the infrastructure layer rather than in application code.

Rate limiting is applied across unauthenticated public endpoints and selected authenticated routes. New high-risk endpoints should include explicit limits or monitoring as part of release review.

11. Secure Development​

API security is integrated into Aventora’s development and release practices.

Requirements​

  • API security reviews performed during development — Material changes to authentication, authorization, public endpoints, webhook handlers, or cross-service trust boundaries are reviewed by engineering personnel before production promotion.
  • Automated security checks executed during the build pipeline — Repository security scan utilities perform static analysis—including dependency audit, secret detection, and custom configuration checks—before production promotion. Manual scan tooling supports optional live probes (auth regression, webhook abuse, CORS checks) for Domain Assistant, Engagement Hub, and the admin dashboard. Findings at high severity or above are remediated before release where scans are executed.
  • Security issues remediated before production deployment — Known high-severity vulnerabilities and exposed secrets are addressed prior to production release or documented with an approved plan and compensating controls.

Pre-deploy validation (for example, Python compile checks and smoke imports) complements security scanning.

Engineers should consult API Security Model when adding cross-service integrations to preserve least-privilege key storage patterns.

12. Third-Party APIs​

Aventora integrates with external providers for telephony, AI, identity, calendar, CRM, and commerce functions.

Requirements​

  • Third-party integrations undergo security review — New vendor API integrations require Engineering Leadership approval before production use. Integration risk is assessed for authentication method, data classification, and failure impact.
  • Minimum required permissions are granted — Provider API keys and OAuth scopes are limited to the capabilities required for the integration (for example, calendar read/write for scheduling, telephony send/receive for messaging).
  • Vendor credentials are protected — Third-party API keys and OAuth tokens are stored using restricted deployment configuration and database access controls. Credentials are transmitted to vendors over TLS.

Webhook integrations validate provider signatures where supported. Integration security controls are documented in Integration Security.

13. API Versioning​

Aventora maintains API stability while allowing controlled evolution.

Versioning strategy​

  • Path and contract versioning — Selected APIs use explicit version segments (for example, Domain Assistant /auth/api/v1/ routes). OpenAPI specifications document REST surfaces for Domain Assistant and Engagement Hub.
  • Backward compatibility where practical — Breaking changes to externally consumed APIs are avoided when possible. Additive changes (new optional fields, new endpoints) are preferred over modifying existing contract behavior.
  • Deprecated APIs retired in a controlled manner — Endpoints marked deprecated remain available during a communicated transition period. Mobile and internal documentation note deprecated routes (for example, legacy voice session APIs superseded by mobile escalation routes). CRM workspace schema migrations follow versioned upgrade tooling tied to APP_VERSION.

Third-party provider API versions (for example, Square, Meta Graph) are pinned via configuration headers or environment variables and updated through controlled maintenance.

Customers integrating directly with Aventora APIs should monitor API reference documentation and release notes for contract changes affecting their integrations.

14. Review​

This API Security Policy is:

  • Reviewed annually by Engineering Leadership, and upon material changes to API architecture, authentication models, public integration surfaces, or hosting providers
  • Owned by Engineering Leadership, which approves updates and communicates significant changes to engineering and operations teams

Questions regarding this policy, deployment-specific API configuration, or security questionnaires may be directed to sales@aventora.ai for routing to the appropriate team.

Alignment with industry guidance​

This policy addresses control themes commonly evaluated in enterprise security programs without asserting formal certification:

GuidanceRelationship
SOC 2Access control, encryption in transit, logging, change management, and vendor integration themes are addressed through the practices described here and in related security documentation
OWASP API Security Top 10Broken authentication, excessive data exposure, lack of resource limiting, improper asset management, and unsafe consumption of third-party APIs are mitigated through the requirements in Sections 3–12
ISO 27001 principlesLeast privilege, secure development, and incident readiness themes are reflected in operational practices; a formal ISMS is not claimed

For control theme alignment, see Compliance and Security Overview.

Changelog​

DateChange
2026-07-20Linked Secure Development Lifecycle (SDLC) Policy.
2026-07-06Linked Application Change Management Policy.
2026-07-06Initial publication of Aventora API Security Policy v1.0.